OpenEuphoria

@[:convert:to_string|]
==== to_string
<eucode>
include std/convert.e
default namespace is convert
include convert.e
namespace convert
public function to_string(object data_in, integer string_quote = 0,
integer embed_string_quote = '"')
</eucode>

Converts an object into a text string.
converts an object into a text string.

===== Parameters:
# ##data_in## : Any Euphoria object.
# ##string_quote## : An integer. If not zero (the default) this will be used to
enclose ##data_in##, if it is already a string.
# ##embed_string_quote## : An integer. This will be used to
enclose any strings embedded inside ##data_in##. The default is '"'

===== Returns:
A **sequence**. This is the string repesentation of ##data_in##.

===== Comments:
* The returned value is guaranteed to be a displayable text string.
* ##string_quote## is only used if ##data_in## is already a string. In this case,
all occurances of ##string_quote## already in ##data_in## are prefixed with
the '\' escape character, as are any preexisting escape characters. Then
##string_quote## is added to both ends of ##data_in##, resulting in a quoted
string.
* ##embed_string_quote## is only used if ##data_in## is a sequence that contains
strings. In this case, it is used as the enclosing quote for embedded strings.

===== Example 1:
<eucode>
include std/console.e -- for display function
include std/convert.e -- for to_string function

display(to_string(12))
display(to_string("abc"))
display(to_string("abc",'"'))
display(to_string(`abc\"`,'"'))
display(to_string({12,"abc",{4.5, -99}}))
display(to_string({12,"abc",{4.5, -99}},,'@')) -- use the @ as substitute for quotes
include std/console.e
display(to_string(12)) --> 12
display(to_string("abc")) --> abc
display(to_string("abc",'"')) --> "abc"
display(to_string(`abc\"`,'"')) --> "abc\\\""
display(to_string({12,"abc",{4.5, -99}})) --> {12, "abc", {4.5, -99}}
display(to_string({12,"abc",{4.5, -99}},,0)) --> {12, abc, {4.5, -99}}
</eucode>

===== Results:
{{{
12
abc
"abc"
"abc\\\""
{12, "abc", {4.5, -99}}
{12, @abc@, {4.5, -99}}
}}}